#12345 ########################

reviewing
Admin Timm Mar10

How to Review Cookbook Entries

About this Page
===============

These notes are suggestions to reviewers of this cookbook. 

These suggestions are tentative- revisions welcome.

Before you Begin
================

All reviewing is done using [http://code.google.com/p/awk/source/browse/#svn/trunk/content the AWK GoogleCode project]. 
Hence,
before you can review anything, you need to have at least commit privileges. To get that permission, send a Google email
to on the of the owners of  that project (owners are listed on the right-hand-side of [http://code.google.com/p/awk/].

Once you have commit privileges, then if you double click
on any line in the  [http://code.google.com/p/awk/source/browse/#svn/trunk/content content], you can add a comment about
that line. 

_Warning: you must_ SAVE _those comments before leaving the page or those comments will be_ LOST.   To save:

+ There is a _save_ button for each comment and, sometimes, a _publish_ button on the right-hand side. 
+ Click on them all. 

Inside the Cookbook
===================

Before you can read the code, you need to know a little bit about its structure.

Code Files
----------

Cookbook authors write their code in a file (e.g.) zTimm1.awk. 

+ At the end of each month, they move on to a new file; e.g. zTimm2.awk.
+ This means that last month's file (in this example, zTimm1.awk) is a stable enough for a review.
+ So make sure you are reviewing last month's code, not stuff that is currently under development.

Pages
-----
The files contain many pages, separated by the magic symbol

 &#35;12345 

After that magic symbol, there is the page name, some keywords, and a title. For example, the 
following page defines some constants used by Cookbook code.

 &#35;12345#####################################################
 
 constants
 Variables Timm Mar10 Sandbox
 
 Defining Constants

All the pages are displayed on the web.

+ If the page name is (e.g.) globals then its web address is [http://awkcookbook.info?globals].

Code and Comments
-----------------

The pages of the Cookbook contain code and comments, all in the same file.

+ _Code_ paragraphs are those whose first line is indented by one space. 
+ Paragraphs with no indentation are _documentation_ paragraphs.
+ There are two other kinds of paragraphs that start with two and three blanks:
  + Paragraphs to be rendered verbatim on the web start with two indents. These _verbatim_ paragraphs are commented out from the source code.
  + Paragraphs defining boring test cases start with three indents. These _demonstration_ paragraphs are not shown on the web.
  + That is, _verbatim_ paragraphs are invisible to the Awk interpreter while _demonstration_ paragraphs are invisible to the web.

Code Generation
---------------

All the code is extracted into one big program: [http://awk.googlecode.com/svn/trunk/src/release/ cookbook.awk]. This means that:

+ All the code has to "play nice with each other"; i.e. new code has to be compatible with existing code.
+ Developers should try to minimize the number of globals (since they can cause unintended interactions). Currently, the globals are defined in [?constants].
+ Developers should not use pattern-directed programming (since the Cookbook is designed to be sub-routines called by higher-level Awk programs).

Test Engine
-----------

The code contains special test engine functions. Cookbook developers use the test engine to check if (e.g.) their lastest change does not break older code.

+ The test engine function names start with an upper case letter.
+ Some of these test engine functions are very tedious and can be hidden from the web by indenting them with three spaces.

How to Review
=============

Set up
------

+ Find a stable developer's code file.
+ For each page in that file,  create one issue "Needs review"

Do
--

+ Find a page that no one else has grabbed.
+ Grab it
  + Make  a new issue "reviewing page X"
  + Make its OpenStatus flag = UnderReview
+ Review it
  + Make comments, change status to "Waiting"
+ Wait a few days
  + Check if a developer has made changes.
  + If not, politely nudge.
  + Change status to "Done" when its all over.

Reviewing
---------

When reviewing the code, please apply the following checklist.

General Items
+++++++++++++

+ Typos
+ Clumsy English, overly-provocative statements,
+ Pages must be categorized:
  + TIN: Descriptive,
  + BRONZE: Sample outputs included in text
  + SILVER: Sample programs in this repository
  + GOLD: Test suite in this repository
  + DIAMOND: Test suites, with expected outputs, in this repository
    + To see if an expected output exists, see [http://code.google.com/p/awk/source/browse/#svn/trunk/src/test/etc/tests here].
+ What else? Please add in the common errors, as you find them.

Page Items
++++++++++

+ Inconsistent headings (pages usually have at least a _PROBLEM_, _SOLUTION_ and _AUTHOR_ header).
+ No tags.
+ Orphaned pages (not linked too by the main site menu pages such as [?strings] or [?numbers].
+ Page is too long (contains multiple entries- should be divided up).
+ Missing "See Also" section (if this page is closely connected to another).
+ Page includes introductory material (each section of the Cookbook such as strings, numbers, etc has its own introductory section. If a page contains intro material that is general to a section, it should be moved to the intro section).
+ What else? Please add in the common errors, as you find them.

HTML Items
++++++++++

+ Line too long error (in the verbatims, causes word wrap)
+ Stray blank space error (paragraphs are delimited by blank lines- and if there is one blank character then the last and next paragraph will run into each other).
+ List item errors (current list item parser gets confused by list items that run over one line)
+ Space, not tab, error (the HTML displays present tabs as one space, mucking up indentation. Tabs should be spaces.)
+ What else? Please add in the common HTML display errors, as you find them.

Awk Code Items
++++++++++++++

+ No test function (note: some code is hard to test; e.g. it takes too long to run, it uses random number generation which can change from platform to platform, it calls a crash)
+ Non-portable constructs (we assume Gawk 3.1.7 or later).
+ length(array) error (this breaks in functions, up until 3.1.8- which is not currently widely used. So length(array) is depreciated). 
+ Locals not defined in function header.
+ Blank lines within code (causes a paragraph break, with strange consequences).
+ Poor indentation
+ What else? Please add in the common Awk code errors, as you find them.

Author
======

Tim Menzies
